OpenEdge Development:<br />Progress Dynamics Advanced Development Defining the Pop-up menu event procedures

Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

Defining the Pop-up menu event procedures

There are several procedures that respond to menu events, including:

Menu Item Choose procedure and using messages in the Message table

Using the Session Manager’s askQuestion procedure

Using the setProfileData procedure

Using the SessionManager’s showMessages procedure

Changing the browser’s COLUMN-MOVABLE attribute

Setting the pop-up menu’s state on menu drop

Testing the extended browser profile data

Menu Item Choose procedure and using messages in the Message table

The eventMenuItemChoose procedure is run when the Save or Reset menu item is chosen. As part of this process, four different messages are used to interact with the user. Two are questions confirming the intent to Save or Reset settings, and the other two are confirmation messages that the Save or Reset succeeded. It is questionable whether either the questions or the confirmation are really appropriate to the user interface, since saving column size and position preferences is not such a major operation that the user should necessarily be forced to OK two message boxes to complete the request. The messages are here more to demonstrate how to use the Session Manager’s message support in your own application code.

To make messages reusable and translatable:

Choose System Message Control in the Progress Dynamics Administration window’s System menu, as shown:

Press Add to bring up Message Maintenance for a new message, as shown:

Each message has a two-part key consisting of a message group and a message number within the group. To keep the new messages distinct from standard system messages, you can put them in a new group, such as BR.

Press the Add button in the Message Control to add the first of your new messages.

Give it a Group of BR and a Number of 1.

Set the default language and check Source Language. At least one message in a group must indicate the source language for that group. For subsequent messages, you need only check Source Language.

Enter a short message text as the Message Summary Description and a longer message in the editor box.

Select a Message Type of Question for the first two messages and Information for the next two.

Define a total of four new messages, as shown:

BR-1 — Save Browser settings?

BR-2 — Reset Browser settings?

BR-3 — Saving Browser settings succeeded.

BR-4 — Resetting Browser settings succeeded.

Return to the Message Control window and filter on the Error Group BR to see all your new messages, as shown:

Now you can use the messages in your application. The code retrieves the browse settings question, if the menu item chosen was SaveBrowseSettings, using the {aferrortxt.i} include file. For more information see OpenEdge Development: Progress Dynamics Basic Development . If the menu item is Reset, then message 2 is retrieved instead, as shown:
IF ( hMenuItem:NAME = "SaveBrowseSettings" ) THEN 
    DO: 
        ASSIGN cMessage = {aferrortxt.i 'BR' '1'} /* "Save browser settings?" */ 
               lDeleteProfileEntry = FALSE. 
…etc. 
Using the Session Manager’s askQuestion procedure

This text is passed to the Session Manager’s askQuestion procedure to present the question to the user. Note that the message text returned by aferrortxt.i is specially formatted to be used by either the askQuestion and showMessage procedures or the checkerr.i include file (which is also described in OpenEdge Development: Progress Dynamics Basic Development ).

Its format is not appropriate to display directly to the user, as shown:
/* Ask user for save or reset confirmation. */ 
    RUN askQuestion IN gshSessionManager ( 
         INPUT cMessage, 
         INPUT "OK,Cancel", 
         INPUT "OK", 
         INPUT "Cancel", 
         INPUT "", 
         INPUT "", 
         INPUT "", 
         INPUT-OUTPUT cAnswer, 
         OUTPUT cButtonPressed). 
    /* Only continue this if user pressed the "OK" button. */ 
    IF ( cButtonPressed <> "OK" ) THEN 
        RETURN. 
This call puts up a message box with OK and Cancel buttons, where OK is the default on Return and Cancel is the default on Escape, and gets back the name of the button the user pressed. If this isn’t the OK button, then the procedure just returns.

The askQuestion call takes these parameters:
RUN askQuestion IN gshSessionManager 
    ( INPUT pcMessageList, 
      INPUT pcButtonList, 
      INPUT pcDefaultButton, 
      INPUT pcCancelButton, 
      INPUT pcMessageTitle, 
      INPUT pcDataType, 
      INPUT pcFormat, 
      INPUT-OUTPUT pcAnswer, 
      OUTPUT pcButtonPressed    ). 
INPUT pcMessageList (CHARACTER) — This is a specially formatted message to display.

INPUT pcButtonList (CHARACTER) — This is a list of the buttons that should appear in the message dialog box.

INPUT pcDefaultButton (CHARACTER) — This is the default button to fire if the user presses RETURN instead of selecting a button.

INPUT pcCancelButton (CHARACTER) — This is the button to fire if the user presses ESCAPE instead of selecting a button.

INPUT pcMessageTitle (CHARACTER) — This optional argument is the title that should appear in the message dialog box. The default is Question.

INPUT pcDataType (CHARACTER) — This optional argument is the data type of the answer to the question, if one is requested.

INPUT pcFormat (CHARACTER) — This optional argument is the format of the answer to the question.

INPUT-OUTPUT pcAnswer (CHARACTER) — The question dialog can, if needed, prompt the user for an answer to the question it poses. This parameter returns the answer to the question being asked. If a nonblank value is passed in, it will be used as an initial answer value. If the data type and format are blank, then no response will be requested and only the button selected with a blank answer will be returned.

OUTPUT pcButtonPressed (CHARACTER) — This is the label of the button that was selected (explicitly or by default if the user pressed RETURN or ESCAPE). If there is no explicit answer to the question, as defined in the pcAnswer, pcDataType, and pcFormat arguments, then the button pressed is effectively the user’s answer. If the button labels are passed in with an ampersand (&), then the button pressed will also contain the ampersand when returned, so you will need to check for this.

If the session is running on the server-side, messages cannot be displayed. Instead they are written to the message log. On the server side, there is no user interface, so the default button label and answer are always returned. On the client side, the messages are displayed in a dialog window. The procedure checks the suppressDisplay property in the Session Manager, and if this is set to YES, it does not display the message but simply passes the message to the log as would be the case for a server-side message. This is useful when your application is running take-on or bulk load procedures client-side.

The askQuestion call in the example looks like this at run time:

Using the setProfileData procedure

The code then gathers up the browse settings for column order and column widths and passes it to the Profile Manager using the procedure setProfileData, as shown:
/* Save column settings to user profile. */ 
    ASSIGN rRowID = ?. 
    RUN setProfileData IN gshProfileManager ( 
        INPUT "Browser", 
        INPUT "Columns", 
        INPUT cProfileKey, 
        INPUT rRowID, 
        INPUT cColumnData, 
        INPUT lDeleteProfileEntry, 
        INPUT "PER" ). 
The setProfileData procedure has the following syntax:
RUN setProfileData IN gshProfileManager 
    ( INPUT pcProfileTypeCode, 
      INPUT pcPRofileCode, 
      INPUT pcProfileDataKey, 
      INPUT prRowid, 
      INPUT pcProfileDataValue, 
      INPUT plDeleteFlag, 
      INPUT pcSaveFlag). 
The setProfileData procedure takes these parameters:

INPUT pcProfileTypeCode (CHARACTER) — As in the previous function.

INPUT pcProfileCode (CHARACTER) — As in the previous function.

INPUT pcProfileDataKey (CHARACTER) — As in the previous function.

INPUT prRowid (ROWID) — As above; if this is passed in, the first three arguments do not apply (and they will be ignored if they are specified).

INPUT pcProfileDataValue (CHARACTER) — This is the character string to assign as the data for this profile entry. The format and content are up to the application that defines and uses the profile code.

INPUT plDeleteFlag (LOGICAL) — If this is TRUE, then the profile data for the matching code will be deleted rather than set. In the case of the example, this value corresponds to the variable lDeleteProfileEntry, which is TRUE is the user selected Reset, and FALSE if the user selected Save.

INPUT pcSaveFlag (CHARACTER) — This parameter should be set to either PER, to mark the settings as Permanent, or SES to save them for the duration of the session only. If the save flag is set to Session, then the user’s session ID is stored in the profile table’s context id field, otherwise the field is left blank to indicate a permanent value.

Note that setProfileData can be used to either set or clear profile data for multiple records that match a partial key passed in. If either one or two of the first three parameters are passed in, but not all three, then all matching profile records are set to the specified profile data value, or they are deleted if the Delete Flag is set.

Back in the example code, the same setProfileData operation is then done for the sorting profile code and the current sort sequence.

Using the SessionManager’s showMessages procedure

Finally, the code retrieves the appropriate confirmation message that the operation succeeded and displays it to the user using the Session Manager’s showMessages procedure, as shown:
/* Show message to user indicating action has been taken. */ 
    IF NOT lDeleteProfileEntry THEN 
                          /* "Saving browser settings succeeded!" */ 
        ASSIGN cMessage = {aferrortxt.i 'BR' '3'}. 
    ELSE 
                          /* "Resetting browser settings succeeded!" */ 
        ASSIGN cMessage = {aferrortxt.i 'BR' '4'}. 
    RUN showMessages IN gshSessionManager ( 
        INPUT cMessage, 
        INPUT "INF", 
        INPUT "OK", 
        INPUT "OK", 
        INPUT "", 
        INPUT "Browser Settings", 
        INPUT NO, 
        INPUT ?, 
        OUTPUT cButtonPressed ). 
The syntax for showMessages is as follows:
RUN showMessages IN gshSessionManager 
    ( INPUT  pcMessageList    
      INPUT  pcMessageType    
      INPUT  pcButtonList     
      INPUT  pcDefaultButton  
      INPUT  pcCancelButton   
      INPUT  pcMessageTitle   
      INPUT  plDisplayEmpty   
      INPUT  phContainer      
      OUTPUT pcButtonPressed). 
These are the parameters for showMessages:

INPUT pcMessageList (CHARACTER) — This is the specially formatted message to display. This can also be a CHR(3)-delimited list of messages.

INPUT pcMessageType (CHARACTER) — This can be any of the various message types except for the special Question type, including Message (MES), Information (INF), Warnings (WAR), Errors (ERR), Serious Halt Errors (HAL) and About Window (ABO).

INPUT pcButtonList (CHARACTER) — This is a list of the buttons that should appear in the message dialog box.

INPUT pcDefaultButton (CHARACTER) — This is the default button to fire if the user presses RETURN instead of selecting a button.

INPUT pcCancelButton (CHARACTER) — This is the button to fire if the user presses ESCAPE instead of selecting a button.

INPUT pcMessageTitle (CHARACTER) — This optional argument is the title that should appear in the message dialog box.

INPUT plDisplayEmpty (LOGICAL) — This flag indicates whether the message dialog box should be displayed even if the message text is empty.

INPUT phContainer (HANDLE) — This is the handle of the container the message dialog box is running from.

OUTPUT pcButtonPressed (CHARACTER) — This returns the label of the button the user selected.

Our sample code results in the following message dialog box:

Changing the browser’s COLUMN-MOVABLE attribute

The procedure eventMenuItemValueChanged is called if the user changes one of the two check-marked menu items (Movable and Sortable). It sets the browse widget’s COLUMN-MOVABLE attribute accordingly. Setting COLUMN-MOVABLE to TRUE allows you to move browse columns by selecting the header, and disables automatic column sorting, as shown:
/* Set COLUMN-MOVABLE off if the Menu Item was "sortable" */ 
    lValue  = hMenuItem:CHECKED. 
    IF ( hMenuItem:NAME = "ColsSortable" ) THEN 
        lValue = NOT lValue. 
    {set BrowseColumnsMovable lValue}. 
    hBrowse:COLUMN-MOVABLE = lValue. 
Setting the pop-up menu’s state on menu drop

The eventPopupMenuMenuDrop procedure is called whenever the user brings up the pop-up menu by right-clicking on the browse. It checks the value of the BrowseColumnsMovable property and sets the two check-marked menu items accordingly, as shown:
{get BrowseColumnsMovable lMovable}. 
IF ( hMenuItem:NAME = "ColsMovable" ) THEN 
    hMenuItem:CHECKED = lMovable. 
ELSE IF ( hMenuItem:NAME = "ColsSortable" ) THEN 
    hMenuItem:CHECKED = NOT lMovable. 
Testing the extended browser profile data

To see what the effect of this custom code is:

Recompile the procedure ry/obj/rydynbrowb.w, the framework’s dynamic browser. Run any container with a dynamic browser in it, for instance, the Customer browse window, as shown:

Bring up the pop-up menu. You can sort on any column by selecting its header. You can resize columns and the new widths will be saved. You can select the Move Columns menu item, grab a column by its header, and move it to a new position, as shown:

Select Save Browser Settings from the menu to save your changes to the Repository so the container looks the same the next time you run it.